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PRIORITY INFORMATION 

[0001] This application claims the benefit of U.S. Provisional Application No. 
60/491,381, filed July 31, 2003. 

5 

BACKGROUND OF THE INVENTION 

Field of the Invention 

10 [0002] This invention relates to computer software, and more particularly to error 
detection in code. 

Description of the Related Art 

15 [0003] Being able to trace an error when it occurs in a program may be as important 
as error handling itself in software development. With C/C++ programs or libraries, what 
is often seen is that a function returns an error status (e.g. an error code) that may tell little 
or nothing about where (i.e. the frame in the call stack) the error occurred. Lacking this 
information may make debugging software and/or identifying the root cause of an error 

20 time consuming and difficult. This may be especially true for errors that are difficult to 
reproduce. Often, C/C++ programs rely on debugging tools to trace errors. These 
debugging tools may require special debug build libraries. In production, typically only 
optimized libraries are deployed. 

25 [0004] The standard C++ language has Exception classes for error handling that may 
be used to provide more information for tracking error conditions. Modern high-level 
languages, e.g. the Java programming language and Microsoft Visual Basic .NET, may 
provide APIs to get the stack trace for exceptions. 
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SUMMARY 

[0005] Embodiments of a flexible error trace mechanism are described. 
Embodiments may be implemented, for example, for C/C++ interface libraries, but 

5 embodiments may also be implemented in other programming languages. Embodiments 
provide a flexible error trace mechanism for C/C++ interface libraries at runtime. 
Embodiments provide a flexible error trace mechanism for C/C++ libraries or a library 
that provides C/C++ interfaces. Embodiments may also be used in programs written in 
other programming languages. Note that C/C++, when used herein, means either the C 

10 programming language, the C++ programming language, or both 

[0006] In one embodiment, when an error occurs in a function call, thread private 
data may be used to record a trace element. A trace element for a function may include or 
indicate one or more of, but is not limited to, the source file name, function name, line 
15 number, product name, and possibly other information that may be used to identify the 
error; for example, a low-level system call error number. 

[0007] A program may call a library function of a library via an API to the library. In 
one embodiment, the library is a C/C++ interface library. If the library function generates 

20 one or more errors, an error trace element may be added to an error trace structure for 
each error generated. In one embodiment, each error trace element includes information 
describing a particular error generated during execution of the library function. The 
library function may complete and return to the calling program. After completion of the 
library function, if the library function generated an error, the program may obtain the 

25 error trace for the library function, for example by calling a library function configured to 
return the error trace. 

[0008] In one embodiment, calling the library function may result in the call of a 
plurality of library functions in a function call stack. For each of the plurality of library 
30 functions, if the library function generates an error, an error trace element may be added 
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to the error trace. 

[0009] The error(s), if any, may be debugged using the information in the obtained 
error trace, if desired. In one embodiment, each error trace element indicates one or more 
5 of a location where the particular error of the error trace element occurred, an error type 
of the particular error, and what the particular error is. In one embodiment, debugging 
may include determining from the error trace element one or more of a location where the 
particular error of the error trace element occurred, an error type of the particular error, 
and what the particular error is. 
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BRIEF DESCRIPTION OF THE DRAWINGS 



[0010] Figure 1 illustrates a system implementing an error trace mechanism according 
to one embodiment. 

5 

[0011] Figure 2 illustrates the operation of the flexible error trace mechanism 
according to one embodiment. 

[0012] Figure 3 is a flowchart of a method for flexible error tracing according to one 
10 embodiment. 

[0013] Figure 4 is a flowchart of a method for flexible error tracing in a library 
according to one embodiment. 

15 [0014] While the invention is described herein by way of example for several 
embodiments and illustrative drawings, those skilled in the art will recognize that the 
invention is not limited to the embodiments or drawings described. It should be 
understood, that the drawings and detailed description thereto are not intended to limit the 
invention to the particular form disclosed, but on the contrary, the intention is to cover all 

20 modifications, equivalents and alternatives falling within the spirit and scope of the 
present invention as defined by the appended claims. The headings used herein are for 
organizational purposes only and are not meant to be used to limit the scope of the 
description or the claims. As used throughout this application, the word "may" is used in 
a permissive sense (i.e., meaning having the potential to), rather than the mandatory sense 

25 (i.e., meaning must). Similarly, the words "include", "including", and "includes" mean 
including, but not limited to. 
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DETAILED DESCRIPTION OF EMBODIMENTS 

[0015] Embodiments of a flexible error trace mechanism are described. 
Embodiments may be implemented, for example, for C/C++ interface libraries, but 
5 embodiments may also be implemented in other programming languages. Embodiments 
provide a flexible error trace mechanism for C/C++ interface libraries at runtime. 
Embodiments provide a flexible error trace mechanism for C/C++ libraries or a library 
that provides C/C++ interfaces. Embodiments may also be used in programs written in 
other programming languages. Note that C/C++, when used herein, means either the C 
10 programming language, the C++ programming language, or both 

[0016] Embodiments may be used in single-threaded or multi-threaded programs. A 
thread may be defined as a sequential execution stream. There may be one or more 
threads per address space. Programs may use multi-threads to accomplish the 

15 performance of several tasks concurrently. In one embodiment, when an error occurs in a 
function call, thread private data may be used to record an error trace element. Note that, 
in other embodiments, the error trace elements may be stored in other locations than 
thread private data. In one embodiment, an error trace may be viewed as a location 
history that indicates one or more locations in potentially difference pieces of code and 

20 that defines the path the code took to generate this particular error. 

[0017] An error trace element for a function may include or indicate one or more of, 
but is not limited to, the source file name, function name, line number, error type, and 
possibly other information that may be used to identify the error; for example, a low-level 

25 system call error number. In one embodiment, the error trace element may include or 
indicate a product name. The product name may be useful in layered software to 
determine which product the error occurred in. In one embodiment, product name 
information may be included in or indicated by the error type. For example, an 'nspr' 
error type used in Sun One Message Queue (MQ) may indicate the error occurred in an 

30 NSPR library. In this example, an MQ application calls API function in the MQ C-API 
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library and the functions in the MQ C-API library in turn calls functions in the NSPR 
library. Note that error type may have other meaning in other implementations. 

[0018] In one embodiment, error trace statements may be macros inserted into the 
5 source code so that the entire error trace in a library may be easily reduced to no-ops at 
compile time. In one embodiment, error trace statements may be defined with different 
debug levels so that an error trace in a debug build may have more function calls recorded 
for a call path than in an optimized build. In one embodiment, the library may provide a 
function to retrieve the error trace for the calling thread when the last library function call 
10 fails (or, in one embodiment, even if it doesn't fail). In one embodiment, the library 
implementer may decide where or how much tracing in a failed call path to record; that is, 
not every function call in a call path may need to be recorded. 

[0019] Figure 1 illustrates a system implementing an error trace mechanism according 
15 to one embodiment. System 400 may be any of various types of devices, including, but 
not limited to, a personal computer system, desktop computer, laptop or notebook 
computer, mainframe computer system, workstation, network computer, or other suitable 
device. System 400 may include at least one processor 402. The processor 402 may be 
coupled to a memory 404. Memory 404 is representative of various types of possible 
20 memory media, also referred to as "computer readable media." Hard disk storage, floppy 
disk storage, removable disk storage, flash memory and random access memory (RAM) 
are examples of memory media. The terms "memory" and "memory medium" may 
include an installation medium, e.g., a CD-ROM or floppy disk, a computer system 
memory such as DRAM, SRAM, EDO RAM, SDRAM, DDR SDRAM, Rambus RAM, 
25 etc., or a non-volatile memory such as a magnetic media, e.g., a hard drive or optical 
storage. The memory medium may include other types of memory as well, or 
combinations thereof. System 400 may couple over a network to one or more other 
devices via one or more wired or wireless network interfaces. 

30 [0020] System 400 may include, in memory 404, code 406 implementing an 
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embodiment of an error trace mechanism 408. Error trace mechanism 408 may provide 
flexible error tracing for code 406 at runtime. Code 406 may be any type of program, 
program component, module, application, etc. In one embodiment, code 406 may be 
implemented in the C/C++ programming language. In other embodiments, code 406 may 

5 be implemented in other programming languages. In one embodiment, code 406 may, for 
example, include a C/C++ interface library that provides the functionality of the error 
trace mechanism 408 to the code 406. Embodiments may also be implemented in 
interface libraries of other programming languages. In one embodiment, error trace 
mechanism 408 may be implemented directly in a program or program component, 

10 function, module, application, etc., rather than being included as part of an interface 
library. 

[0021] Figure 2 illustrates the operation of the flexible error trace mechanism 
according to one embodiment. One or more threads 102 may be executing within a 

15 program. Each thread private data 100 is a storage area (memory) specific to a particular 
thread. Each thread may store and access data in its associated thread private data 100 for 
the thread. In one embodiment, when error traces are stored using thread private data, all 
error trace elements generated for a particular thread are recorded in the thread's private 
data area. Thus, each thread private data 100 may store error traces 104, if any, for its 

20 associated thread. Each error trace 104 may include one or more elements 106. If no 
error has been encountered in a thread, or if the error trace has been cleared (e.g. by a call 
to ClearErrorTrace(), then an error trace 104 may be empty or NULL. 

[0022] In the function call stack, an API call to a function (A()) may be made, for 
25 example by a function in user code. From that API call, a series of library functions may 
be called (e.g. B(), C() and D()) in the thread. If one or more of the function calls fails, 
then an error trace element may be written to the error trace 104 for the thread, for 
example through the failing function calling a SetErrorTraceElement() function of the 
library upon detecting the error. In one embodiment, an error trace 104 may then be 
30 obtained by the calling function, e.g. a function in user code, for example by calling a 
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GetErrorTrace() function of the library. In one embodiment, the called API function (e.g. 
function A()) may return an error code. The returned error code may be checked and, if 
the error code indicates that the called function (or any functions in the function call 
stack) failed, then the calling function may obtain the error trace 104 (e.g. by calling a 

5 GetErrorTrace() function or its equivalent). In another embodiment, an error trace 104 
may be returned by the called API function, in this example function A(). The error trace 
104 may include one or more elements added to the error trace 104 by called library 
functions of the function call stack that encountered errors. If no functions in the function 
call stack encountered an error, then the error trace 104, if obtained, may indicate that no 

10 functions failed (e.g. via the array of trace elements in error trace 104 being NULL). The 
error trace 104 may then be evaluated, displayed, or otherwise used for debugging 
purposes, and, for example, may be used to determine one or more of, but not limited to, 
where (e.g. which method or function, file, and/or line number) an error or errors 
occurred, the error type of error(s) that occurred, and what the error(s) was (e.g. via error 

15 codes). 

[0023] There are different ways in which multiple functions may be called in an error 
trace. For example, a. function A() may get called, and A() in turn calls functions x(), y() 
and z(). If x(), y() or z() fails, A() may record an error trace element for each of the 

20 functions. Alternatively, x(), for example, may record a error trace element, or both A() 
and x() may record an error trace element. This may be useful in identifying an error 
location when A() may call x() in multiple places in A(), and A() has different execution 
branches depending on some condition variable. As another example, function A() may 
get called, and A() calls x(), and x() in turn calls y(), and y() in turn calls z(). In this 

25 example, any of these functions may record an error trace element. 

[0024] Note that, in one embodiment, a program may include two or more threads 
running simultaneously (e.g. threads 102A and 102B), and each thread may be recording 
some or all errors that occur in a thread-specific error trace 104. 

30 
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[0025] The following is an exemplary API that provides an embodiment of the error 
trace mechanism, and includes a library code and user code example of using the error 
trace mechanism provided by the API. This example is from a message queue (MQ) API 
(e.g. Sun One Message Queue (MQ)), and is written in the C/C++ programming 
5 language, and is not intended to be limiting. Embodiments of the error trace mechanism 
may be similarly implemented in other APIs, or in other code structures. The following is 
an exemplary API definition (header file) that includes the error trace mechanism: 

#ifndef ERRORTRACE_H 
10 #define ERRORTRACEJH 

ifdef cplusplus 

extern "C" { 

#endif /* cplusplus */ 

struct ErrorTrace { 

MQBool usable; 
MQUint32 num_elements; 
MQUint32 num_allocated; 
char **trace; 

}; 

/* get the errorTrace 7 

MQStatus getErrorTrace (ErrorTrace ** trace); 

r set an element in the ErrorTrace structure. This adds an element to char **trace, an 
array of error trace elements where each error trace element is represented as a string, in the 
ErrorTrace. Note that num_elements is also incremented 7 

MQStatus setErrorTraceElement ( const char * method, 

const char * file, 
MQInt32 lineNumber, 
const char * errorType, 
MQUint32 errorCode); 

35 r clear ErrorTrace; if 'all' is true, clear thread private data as well 7 



15 



20 



25 



30 
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MQStatus clearErrorTrace (MQBool all); 

ifdef cplusplus 

} 

#endif I* _cplusplus */ 
#endif /* ERRORTRACE_H 7 

[0026] In one embodiment, getErrorTrace() returns the current thread's current error 
trace in string format as defined below (or NULL if no error trace is available). In one 
embodiment, a C/C++ API internal function may decide when or whether to record an 
error trace element in the error trace in case of an error. In one embodiment, error trace is 
stored as thread private data. 

[0027] In one embodiment, the format of an error trace string may be: 

<method name>:<file name>:<line number>:<error type>:<error code>:<error string> 

where: 

• <method name> is the name of the method in which the error trace element was 
added. 

• <file name> is the name of the file which contains the source for the indicated 
method. 

• <line number> is the line number where the particular error occurred. 

• <error type> is a type for the error. In one embodiment, error type may indicate 
an application, library, or other module in which the error occurred. In one 
embodiment, product name information may be included in or indicated by the 
error type, e.g. mq, nspr, nss, or os. Note that error type may have other meanings 
in other implementations. 

• <error code> is a code that indicates the specific error that the error trace is 
reporting. 

• <error string> is an (optional) string that may indicate other information about the 
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error. 



10 



Note that other embodiments may use other formats for the error trace string. 

[0028] In one embodiment, the caller may be responsible for freeing the returned 
string (e.g. an MQString) by calling a function to free the string (e.g. MQFreeStringO). In 
one embodiment, the current thread's error trace may be automatically cleared on the next 
C-API method call, and may also be cleared by other function calls (e.g. in an 
MQCloseConnection() call). In one embodiment, the error trace string may be private. 

[0029] The following is an API library code example function according to one 
embodiment: 



Error A() 

15 { 

static const char FUNC_NAME[] = "A"; 
Error errorCode; 

CLEAR_ERROR_TRACE(PR_FALSE); 
20 errorCode = b(); 



if (errorCode != SUCCESS) { 

MQ_ERROR_TRACE(FUNC_NAME, errorCode); 

} 



25 



[0030] The following is a user code example according to one embodiment: 

30 

r call the API function A() 7 
Error errorCode = A(); 
/* check the return status 7 
if (errorCode != SUCCESS) { 
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r get the error trace 7 

ErrorTrace errorTrace = getErrorTrace(); 

5 r process as needed according to the returned errorTrace */ 

} 



10 

[0031] The following is an example of an error trace output that may be obtained 
when an exemplary API call (in this example, an API function MQCreateConnection()) 
fails: 

15 connect:../ ../../ ../src/share/cclient/io/TCPSocket.cpp:1 73:mq:21 03 

connect:../ ../ ../ ../src/share/cclient/io/TCPSocket.cpp:195:mq:2103 
readBrokerPorts:../ ../ ../ ../src/share/cclient/client/PortMapperClient.cpp:48:mq:2103 
connect:../ ../ ../ ../src/share/ccIient/client/protocol/TCPProtocolHandler.cpp.1 1 1 : 
connectToBroker:../ ../ ../ ../src/share/cclient/client/Connection.cpp:416:mq:2103 

20 openConnection:../ ../ ../ ../src/share/cclient/client/Connection.cpp:247:mq:1900 

MQCreateConnection:../ ../ ../ ../src/share/cclient/cshim/iMQConnectoinShim.cpp:120:mq: 

[0032] Figure 3 is a flowchart of a method for flexible error tracing according to one 
25 embodiment. As indicated at 200, a program may call a function that implements an 
embodiment of the error trace mechanism as described herein. In one embodiment, the 
function may be a function of a library called via an API to the library. In one 
embodiment, the library may be a C/C++ interface library. 

30 [0033] As indicated at 202, after the function completes, the program may determine 
if the function generated an error. As indicated at 204, if the function generated an error, 
the program may obtain an error trace for the function. In one embodiment, the obtained 
error trace may include one or more error trace elements, and each error trace element 



Atty. Dkt. No.: 5681 -6940 1/SUN030 138 



12 



Meyertons, Hood, Kivlin, Kowert, & Goetzel, P.C. 



includes information describing a particular error generated during execution of the 
function. 



[0034] In one embodiment, the function may call a plurality of functions in a function 
5 call stack. For each of the plurality of functions, if the particular function generates an 
error, an error trace element may be added to the error trace. 

[0035] As indicated at 206, the error(s) may be debugged using the information in the 
obtained error trace, if desired. In one embodiment, each error trace element indicates 

10 one or more of a location where the particular error of the error trace element occurred, an 
error type of the particular error, and what the particular error is. In one embodiment, the 
location of the particular error may include one or more of a function name, a source file 
name, and a line number where the particular error occurred. In one embodiment, 
debugging may include determining from the error trace element one or more of a 

15 location where the particular error of the error trace element occurred, an error type of the 
particular error, and what the particular error is. 

[0036] Figure 4 is a flowchart of a method for flexible error tracing in a library 
according to one embodiment. In one embodiment, the library is a C/C++ interface 

20 library. As indicated at 300, a program may call a library function of a library via an API 
to the library. As indicated at 302, if the library function generates one or more errors, an 
error trace element may be added to an error trace for each error generated, as indicated at 
304. In one embodiment, each error trace element includes information describing a 
particular error generated during execution of the library function. As indicated at 306, 

25 the library function may complete and return to the calling program. After completion of 
the library function, if the library function generated an error as indicated at 308, the 
program may obtain the error trace for the library function as indicated at 310, for 
example by calling a GetErrorTrace() function of the library. 

30 [0037] In one embodiment, calling the library function may result in the call of a 
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plurality of library functions in a function call stack. For each of the plurality of library 
functions, if the library function generates an error, an error trace element may be added 
to the error trace. 

5 [0038] As indicated at 312, the error(s) may be debugged using the information in the 
obtained error trace, if desired. In one embodiment, each error trace element indicates 
one or more of a location where the particular error of the error trace element occurred, an 
error type of the particular error, and what the particular error is. In one embodiment, the 
location of the particular error may include one or more of a function name, a source file 
10 name, and a line number where the particular error occurred. In one embodiment, 
debugging may include determining from the error trace element one or more of a 
location where the particular error of the error trace element occurred, an error type of the 
particular error, and what the particular error is. 

15 Conclusion 

[0039] Various embodiments may further include receiving, sending or storing 

instructions and/or data implemented in accordance with the foregoing description upon a 
carrier medium. Generally speaking, a carrier medium may include storage media or 
20 memory media such as magnetic or optical media, e.g., disk or CD-ROM, volatile or non- 
volatile media such as RAM (e.g. SDRAM, DDR SDRAM, RDRAM, SRAM, etc.), 
ROM, etc. as well as transmission media or signals such as electrical, electromagnetic, or 
digital signals, conveyed via a communication medium such as network and/or a wireless 
link. 

25 

[0040] The various methods as illustrated in the Figures and described herein 
represent exemplary embodiments of methods. The methods may be implemented in 
software, hardware, or a combination thereof. The order of method may be changed, and 
various elements may be added, reordered, combined, omitted, modified, etc. 

30 
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[0041] Various modifications and changes may be made as would be obvious to a 
person skilled in the art having the benefit of this disclosure. It is intended that the 
invention embrace all such modifications and changes and, accordingly, the above 
description to be regarded in an illustrative rather than a restrictive sense. 
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